Gets information about the files and directories in a file catalog.

OSErr PBGetCatInfoAsync (
    CInfoPBPtr paramBlock
);

Parameter descriptions

paramBlock

A pointer to a catalog information parameter block.

function result

A result code.

DISCUSSION

The PBGetCatInfoAsync function returns information about a file or directory, depending on the values you specify in the ioFDirIndex, ioNamePtr, ioVRefNum, and ioDirID or ioDrDirID fields. If you need to determine whether the information returned is for a file or a directory, you can test bit 4 of the ioFlAttrib field; if that bit is set, the information returned describes a directory.

The PBGetCatInfoAsync function selects a file or directory according to these rules:

• If the value of ioFDirIndex is positive, PBGetCatInfoAsync returns information about the file or directory whose directory index is ioFDirIndex in the directory specified by ioVRefNum (this will be the root directory if a volume reference number is provided).
• If the value of ioFDirIndex is 0, PBGetCatInfoAsync returns information about the file or directory specified by ioNamePtr in the directory specified by ioVRefNum (again, this will be the root directory if a volume reference number is provided).
• If the value of ioFDirIndex is negative, PBGetCatInfoAsync ignores ioNamePtr and returns information about the directory specified by ioDrDirID.

The fields of the parameter block which are used by both files and directories are:

• ioCompletion

  On input, a pointer to a completion function.

• ioResult

  On output, the result code of the function.

• ioNamePtr

  A pointer to a pathname. For files, the name of the file is returned in this field, if the file is open. If you do not want the name of the file returned, pass NULL in this field.

• ioVRefNum

  On input, a volume specification.

• ioFDirIndex

  On input, an index.

• ioFlAttrib

  On output, the file or directory attributes. For files, see HFileInfo) for the meaning of the bits in this field.

  For directories, the attributes encoded by bits in this field have these meanings

• Bit 0 is set if the directory is locked.
• Bit 1 is reserved.
• Bit 2 is set if the directory is within a shared area of the directory hierarchy.
• Bit 3 is set if the directory is a share point that is mounted by some user.
• Bit 4 is set if the item is a directory.
• Bit 5 is set if the directory is a share point.
• Bits 6-7 are reserved.

These bits in the ioFlAttrib field for directories are read-only. You cannot alter directory attributes by setting these bits using PBSetCatInfoAsync. Instead, you can call PBHSetFLockAsync and PBHRstFLockAsync to lock and unlock a directory, and PBShareAsync and PBUnshareAsync to enable and disable file sharing on local directories.

For files, these fields of the parameter block are also used:

• ioFRefNum

  On output, a file reference number. If the file is open, the reference number of the first access path found is returned here.

• ioFlFndrInfo

  On output, information used by the Finder.

• ioDirID

  On input, a directory ID. On output, the file ID. You might need to save the value of ioDirID before calling PBGetCatInfoAsync if you make subsequent calls with the same parameter block.

• ioFlStBlk

  On output, the first allocation block of the data fork.

• ioFlLgLen

  On output, the logical end-of-file of the data fork.

• ioFlPyLen

  On output, the physical end-of-file of the data fork.

• ioFlRStBlk

  On output, the first allocation block of the resource fork.

• ioFlRLgLen

  On output, the logical end-of-file of the resource fork.

• ioFlRPyLen

  On output, the physical end-of-file of the resource fork.

• ioFlCrDat

  On output, the date and time of creation.

• ioFlMdDat

  On output, the date and time of the last modification.

• ioFlBkDat

  On output, the date and time of the last backup.

• ioFlXFndrInfo

  On output, additional information used by the Finder.

• ioFlParID

  On output, the directory ID of the parent directory.

• ioFlClpSiz

  On output, the file’s clump size.

For directories, these fields of the parameter block are also used:

• ioACUser

  On output, the directory access rights. The PBGetCatInfoAsync function returns the directory access rights only for shared volumes. As a result, you should set this field to 0 before calling PBGetCatInfoAsync.

• ioDrUsrWds

  On output, information used by the Finder.

• ioDrDirID

  The directory ID.

• ioDrNmFls

  On output, the number of files in the directory.

• ioDrCrDat

  On output, the date and time of creation.

• ioDrMdDat

  On output, the date and time of the last modification.

• ioDrBkDat

  On output, the date and time of the last backup.

• ioDrFndrInfo

  On output, additional information used by the Finder.

• ioDrParID

  On output, the directory ID of the parent directory

With files, PBGetCatInfoAsync is similar to PBHGetFInfoAsync but returns some additional information. With directories, PBGetCatInfoAsync returns information such as the directory attributes and, for server volumes, the directory access privileges of the user.

You can also use PBGetCatInfoAsync to determine whether a file has a file ID reference. The value of the file ID is returned in the ioDirID field. Because that parameter could also represent a directory ID, call PBResolveFileIDRefAsync to see if the value is a real file ID. If you want to determine whether a file ID reference exists for a file and create one if it doesn’t, use PBCreateFileIDRefAsync, which will either create a file ID or return fidExists.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)